0
Fork 0
mirror of https://github.com/twbs/bootstrap.git synced 2026-11-16 06:58:43 +00:00
bootstrap/AGENTS.md
Mark Otto f9a7a8941e
Unify chip input and editable Combobox (#43300)
* fix(combobox): support native form values and events

Multiple selections now submit one field per value. Commas stay in the
value, and an empty multiple selection submits no entries. Reuse an
explicit hidden input without removing application-owned fields.

Keep a stable field for input and change listeners. Sync fields before
notifications, restore initial selections on reset, and follow disabled
state and form ownership. Document the update and disposal contracts.

Forward Menu lifecycle events after its transitions. Keep native search
editing keys and cover the sticky search padding with logical CSS.

* feat(combobox): combine editable selection and chip entry

Search and select values from one editable field. Multiple selections
render as removable chips, and explicit free entry supports tags. Keep
query text separate from committed values and preserve native form data.

Use the existing Menu for positioning and lifecycle. Keep focus in the
editor while suggestions are highlighted. Preserve chip nodes, caret
positions, reset behavior, and input-method text during reconciliation.

Retire the separate Chips plugin and chip-input control. Keep static
chip styles and button-triggered Combobox markup. Document the alpha 2
markup, token, method, and event migration.

* fix(combobox): match chip fields to the default input height

Multiple values should fit the same row height as a normal input.
Use shared input spacing and typography, with smaller contextual chips.
Let the field grow when its values wrap.

Replace the text dismiss glyph with the SVG from the chip documentation.
Keep the named removal button and existing chip interaction behavior.

* fix(combobox): separate chip icon size from its hit area

Render the dismiss icon at 12px inside a 24px removal button. Move chips
closer to the field's inline start while keeping normal text padding
for an empty editor. Use logical spacing so the inset follows RTL.

* fix(combobox): tighten chip dismiss spacing

Use negative inline margins to bring the dismiss button closer to the
label and chip edge. Keep its 24px hit area and 12px SVG artwork.

* fix(combobox): derive chip corners from the field radius

Use a nested chip radius based on the wrapping field's radius, border,
and inset. Clamp the result at zero so square fields keep square chips.

* fix(combobox): balance chip insets within the field

Match the field's inline padding to its vertical padding when chips
are present. Derive chip corners from that inset and pull the dismiss
button's end margin in another 2px without reducing its hit area.

* fix(combobox): soften chip corners within balanced fields

Use half the field radius for chips so equal input padding does not
leave their corners nearly square. Keep square fields square.

* fix(combobox): restore chip selection and keyboard behavior

Highlight chips with the filled active state when users navigate or
select them. Restore modifier clicks, anchored ranges, select-all, and
deletion of highlighted chips. Keep native query editing and RTL keys.

Keep chip highlights separate from committed values. Report UI selection
through select.bs.combobox and restore the chip selection methods on
Combobox. Bulk removal honors each cancellation and emits one value
change before recovering focus.

Document the restored interaction and alpha migration. Cover range
anchors, duplicate values, disabled chips, reset, and disposal.

* fix(combobox): select chips on every focus path

Tabbing to a chip's remove button or focusing a chip directly should
show its primary selected state. Apply that highlight without changing
committed values, and dismiss the suggestion popup.

Guard focus controlled by range navigation and modifier clicks so it
does not collapse or undo the user's chip selection.

* fix(combobox): suppress inner chip focus outlines

Keep the filled selected chip and the wrapping field's focus ring as
focus indicators. Suppress the nested outlines on chips and their
remove buttons during keyboard navigation.

* fix(combobox): guard form and editor edge cases

Selection callbacks can change or dispose the component before an outer
operation completes. Stop stale selection and focus work after those
callbacks, and keep pending popup sizing from changing disposed markup.

Handle native composition events through the shared event system. Keep
unfinished input out of blur commits, reconcile completed composition,
and preserve focus after the editor loses it. Let the IME handle its
keys in both Combobox and Menu.

Follow external reset forms without a backing field, omit disabled
single options, and clear references to removed or disabled suggestions.
Add regressions and clarify the synchronous form update requirement.

* docs(chips): move standalone chips to Components

Chips can stand alone or appear within a form component. Place their
docs in Components and describe that wider use. Keep the old Forms URL
as a redirect, and update navigation and cross-links.

* fix(chips): limit hover feedback to interactive chips

Static chips change color and show a pointer cursor on hover, even
when they have no action. Keep static chips neutral and apply hover
feedback to links, buttons, and Combobox chips. A dismiss button keeps
its own hover state without changing the whole chip.

Add interactive examples and correct the documented CSS layer. Allow
for the extra selectors in the unminified CSS bundle budget.

* docs(combobox): lead with editable examples

Show search and selection in the input from the first example. Use
inputs for the shared examples and group the button variants together.
Use the editable markup in the form and setup guidance too.

* docs(combobox): restore the overview feature list

Describe editable inputs and button toggles in the original overview.
Include chips, free entry, form submission, and selection events.

* docs(combobox): preserve example indentation

Match the form field examples by adding the source indentation that
MDX strips. Record the convention in the docs guidance.

* fix(combobox): focus search directly when opening

Clicking a searchable combobox moved focus to the trigger before
the opening animation moved it to search.

Focus search as soon as the menu opens. Keep the trigger in the
tab order and return focus to it on Escape.

* docs(combobox): style the Language example label

* ci(combobox): fix bundle budgets and spelling

Round the three JavaScript bundle limits up to the next quarter
kilobyte to account for the search focus changes. Reword the docs
indentation rule so it passes the spelling check.

* fix(combobox): preserve resets and expose selection state

A canceled second reset could discard a completed reset. Keep each
pending reset until its own callback runs. Give button-mode options
listbox roles, handle Escape on the toggle, and restore chip focus
rings. Keep long values inside the field and use shared state tokens.

* fix(combobox): fit chips to the shared control size

Compact controls were 30px tall, but their fixed-height chips made
the multiple-selection field 34px tall. Derive chip and dismiss-button
heights from the space left by the control padding and borders. Check
compact, default, and spacious controls in the browser.

* docs(combobox): redirect chip input readers to the merged component

The former chip input page now points to Combobox. Explain the
consolidation at the top of that page and link the migration steps
for existing chip inputs.

* chore(combobox): account for the current main bundle size

The rebased build includes the merged Range and hash-link fixes.
Raise the three affected limits to the next standard budget step.
2026-11-12 12:48:15 -08:00

7.9 KiB

AGENTS.md

Guidance for AI coding agents working in this repository. Tool-agnostic; CLAUDE.md points here.

Bootstrap v6.0.0-alpha.1 — CSS/JS framework. Sass source in scss/, TypeScript source in js/src/, docs site in site/ (Astro 5 + MDX).

Quick commands

  • npm start — dev server (watch + Astro on port 9001)
  • npm run dist — full CSS + JS build
  • npm run css — compile, prefix, minify CSS
  • npm run js — compile + minify JS
  • npm run css-lint / npm run js-lint — lint
  • npm run docs-build — build docs site
  • npm test — full test suite (lint + dist + tests + docs)

Writing style

Use ASD-STE100 Simplified Technical English for all prose: replies to the user, docs, code comments, commit messages, and PR text.

  • Write short sentences. Use approximately 20 words or fewer.
  • Give one instruction per sentence.
  • Use the active voice. Name the actor.
  • Use simple verbs. Do not use a complex verb when a simple one works.
  • Use one term for one thing. Keep terms the same across the project.
  • Keep paragraphs short. Cover one topic per paragraph.

Reply length

Be extremely brief. Report the result, not the journey.

  • Target 75 words or fewer. Hard cap 150 words, and only for a genuinely multi-part answer.
  • Answer in the first sentence. Then stop.
  • Give one supporting fact per claim, at most. Cut the rest.
  • Do not narrate your process, tool calls, or verification steps. Report a check only when it failed or changed the outcome.
  • Do not restate the work you just did. The user reads the diff, the commit, and the PR.
  • State a finding once. Never repeat it in a summary or closing line.
  • No headings. No tables. Use a list of 5 items or fewer only when the answer is a real list.
  • Cut praise, apologies, hedging, and filler such as "great question" or "worth noting".
  • Do not explain what you did not do, or list caveats the user did not ask about.
  • Do not offer next steps unless the user asks or the work is blocked.
  • Expand only when the user asks for detail, or asks you to teach.

Teaching

Act as a teacher for JavaScript, TypeScript, React, and all JavaScript-family topics.

  • When the work hits a new problem, concept, or language feature, stop and explain it.
  • Keep each explanation short and plain. Define jargon on first use.
  • Use a small code example when it makes the idea clear.
  • Assume strong HTML/CSS knowledge. Do not assume deep JS internals knowledge.

SCSS conventions

  • Variable naming: $component-state-property-size (e.g., $nav-link-disabled-color)
  • Module system: @use / @forward only — never @import
  • Token system: component tokens are SCSS maps of CSS custom properties, merged via defaults(), output via @include tokens($map) on the component root selector
  • Disallowed: raw border-radius / transition properties (use mixins), lighten() / darken(), border: none / outline: none
  • Order: @use → @forward → $variables → --custom-properties → declarations → rules
  • Variables use !default (except locals)
  • CSS layers: colors, config, root, reboot, layout, content, forms, components, custom, helpers, utilities
  • Logical properties: prefer padding-inline-start over padding-left, etc.
  • Modern CSS: color-mix(), light-dark(), range media queries (@media (width >= 1024px))
  • Doc markers: // scss-docs-start name / // scss-docs-end name for docs extraction

JavaScript/TypeScript conventions

  • Source is TypeScript (js/src/**/*.ts, entry js/src/index.ts); ESM-only, no semicolons, 2-space indent
  • Imports use .js extensions (standard TS ESM style); Rolldown resolves them to .ts via resolve.extensionAlias, Vitest via the tsResolve plugin in js/tests/vitest.config.mts
  • Dist builds use Rolldown (build/rolldown.config.mjs, build/build-plugins.mjs) with built-in TS transforms; build/browser-targets.mjs derives the browser floors from .browserslistrc at build time, so there is nothing to keep in sync. Rollup and Babel are gone from the repo — Vitest transforms the specs itself
  • Strict tsconfig with verbatimModuleSyntax + erasableSyntaxOnly; tsc only type-checks and emits .d.ts (npm run js-typecheck, npm run js-emit-types)
  • Components extend BaseComponent (which extends Config); per-component config type XxxConfig typed off Default, refined on the class via protected declare _config: XxxConfig
  • Instance fields use declare (no runtime emit); constructor element param stays optional to keep typeof Component assignable to typeof BaseComponent
  • Every _-prefixed instance member is protected (never private, so subclasses keep access); public API methods and statics stay public. This keeps the internals out of the published .d.ts surface
  • Constants: NAME, DATA_KEY, EVENT_KEY, VERSION
  • DOM utilities via dom/event-handler.ts, dom/selector-engine.ts, dom/manipulator.ts
  • Floating UI for positioning (dropdown, tooltip, popover)
  • Tests: Vitest browser mode (real Chromium via Playwright), config in js/tests/vitest.config.mts, specs in js/tests/unit/*.spec.js (plain JS, bundled against the TS sources). js/tests/vitest-setup.js maps the Jasmine API the specs are written against onto Vitest — note spyOn stubs by default, unlike vi.spyOn. Async specs return a promise; Vitest 4 dropped done. Coverage is Istanbul over all of js/src, thresholds 90/88/90/90
  • Type-level API tests in js/tests/types/ — api.ts checks the source (npm run js-typecheck), consumer.ts checks the shipped js/dist/*.d.ts through the package exports map (npm run js-typecheck-dist, after the build). Keep the two in sync

Docs conventions

  • Astro 5 + MDX in site/src/content/docs/
  • Frontmatter schema: title (required), description (required), toc, aliases, added, mdn, reference, etc.
  • Shortcodes: Example, Callout, Code, Details
  • For multiline <Example code={...}> template literals that start on the same line as the shortcode, add two extra spaces to each following line of code. Top-level markup starts with two spaces in the source, and its children start with four. The rendered snippet removes the extra level. Follow site/src/content/docs/forms/field.mdx and check the rendered code before committing.
  • Internal links: [[docsref:/path/]]
  • JS component "Dependencies" tables are auto-generated — add a ### Dependencies heading with <JsDependencies component="<js-src-basename>" /> (before ### Options) on any doc for a js/src/*.ts component. The table is derived at build time by walking the component's import graph in site/src/libs/js-dependencies.ts; never hand-write the file list. When a new source file or third-party package enters the graph, add its human-readable label to FILE_DESCRIPTIONS / PACKAGE_DESCRIPTIONS in that lib (the build throws if a label is missing).

Formatting

  • 2 spaces, UTF-8, LF line endings, trim trailing whitespace, final newline
  • Preserve smart punctuation (curly apostrophes U+2019, curly quotes) — never replace with ASCII equivalents
  • Use StrReplace for targeted edits; avoid full-file rewrites on MDX files to protect typography

Workflow

  • Validate after changes: npm run css-lint, npm run js-lint, npm run dist, npm run docs-build
  • Keep config files in sync: config.yml, site/src/libs/config.ts (Zod schema), build/rolldown.config.mjs, build/generate-sri.mjs, package.json
  • For rebases/conflicts: favor base branch structure, layer feature changes on top

Commits & PRs

  • Commit messages: direct, succinct prose explaining why the change was made.
  • PR descriptions: direct bulleted lists, minimal fluff — one bullet per notable change.
  • Reference related issues/PRs explicitly with Fixes #{issue}, Closes #{issue}, or Supersedes #{pr}.
  • No "Test plan" section and no extra headings — just the bullets and the references.

Do not edit

Built output in dist/, _site/, js/dist/ — these are generated.